home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / JFC.bin / Action.java < prev    next >
Text File  |  1998-06-30  |  6KB  |  125 lines
  1. /*
  2.  * @(#)Action.java    1.9 98/02/18
  3.  * 
  4.  * Copyright (c) 1997 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  */
  20. package com.sun.java.swing;
  21.  
  22. import java.awt.*;
  23. import java.awt.event.*;
  24. import java.beans.*;
  25.  
  26. /**
  27.  * The JFC Action interface provides a useful extension to the ActionListner
  28.  * interface in cases where the same functionality may be accessed by
  29.  * several controls.
  30.  * <p>
  31.  * In addition to the <code>actionPerformed</code> method
  32.  * defined by the ActionListener interface, this interface allows the
  33.  * application to define, in a single place:
  34.  * <ul>
  35.  * <li>One or more text strings that describe the function. These strings
  36.  *     can be used, for example, to display the flyover text for a button
  37.  *     or to set the text in a menu item.
  38.  * <li>One or more icons that depict the function. These icons can be used
  39.  *     for the images in a menu control, or for composite-entries in a more
  40.  *     sophisticated user-interface.
  41.  * <li>The enabled/disabled state of the functionality. Instead of having
  42.  *     to separately disable the menu-item and the toolbar-button, the
  43.  *     application can disable the function that implements this interface.
  44.  *     All components which are registered as listeners for the state-change
  45.  *     then know to disable event-generation for that item and to modify the 
  46.  *     display accordingly.
  47.  * </ul>
  48.  * Containers in the Swing set like menus and toolbars know how to add an
  49.  * Action object, as well as other components, using a version of the 
  50.  * <code>add</code> method. When an Action object is added to such a
  51.  * container, the container:
  52.  * <ol type="a">
  53.  * <li>Creates a component that is appropriate for that container 
  54.  *     (a toolbar creates a button component, for example).
  55.  * <li>Gets the appropriate property(s) from the Action object to customize
  56.  *     the component (for example, the icon image and flyover text).
  57.  * <li>Checks the intial state of the Action object to determine if it is
  58.  *     enabled or disabled, and renders the component in the appropriate
  59.  *     fashion.
  60.  * <li>Registers a listener with the Action object so that is notified of
  61.  *     state changes. When the Action object changes from enabled to disabled,
  62.  *     or back, the container makes the appropriate revisions to the
  63.  *     event-generation mechanisms and renders the component accordingly.
  64.  * </ol>
  65.  * For example, both a menu item and a toolbar button could access a
  66.  * <code>Cut</code> action object. The text associated with the object is 
  67.  * specified as "Cut", and an image depicting a pair of scissors is specified 
  68.  * as its icon. The <code>Cut</code> action-object can then be added to a
  69.  * menu and to a toolbar. Each container does the appropriate things with the
  70.  * object, and invokes its <code>actionPerformed</code> method when the
  71.  * component associated with it is activated. The application can then disable 
  72.  * or enable the application object without worrying about what user-interface
  73.  * components are connected to it.
  74.  * <p>
  75.  * This interface can be added to an existing class or used to create an
  76.  * adapter (typically, by subclassing AbstractAction). The Action object
  77.  * can then be added to multiple action-aware containers and connected to
  78.  * Action-capable components. The GUI controls can then be activated or
  79.  * deactivated all at once by invoking the Action object's <code>setEnabled</code>
  80.  * method.
  81.  *
  82.  * @version 1.9 02/18/98
  83.  * @author Georges Saab
  84.  * @see AbstractAction
  85.  */
  86. public interface Action extends ActionListener {
  87.     /**
  88.      * Useful constants that can be used as the storage-retreival key 
  89.      * when setting or getting one of this object's properties (text
  90.      * or icon).
  91.      */
  92.     public static final String DEFAULT = "Default";
  93.     public static final String NAME = "Name";
  94.     public static final String SHORT_DESCRIPTION = "ShortDescription";
  95.     public static final String LONG_DESCRIPTION = "LongDescription";
  96.     public static final String SMALL_ICON = "SmallIcon";
  97.  
  98.     /**
  99.      * Puts/gets one of this object's properties
  100.      * using the associated key.  If the value has
  101.      * changed, a PropertyChangeEvent will be sent
  102.      * to listeners.
  103.      */
  104.     public Object getValue(String key);
  105.     public void putValue(String key, Object value);
  106.  
  107.     /**
  108.      * Sets/tests the enabled state of the Action. When enabled,
  109.      * any component associated with this object is active and
  110.      * able to fire this object's <code>actionPerformed</code> method.
  111.      */
  112.     public void setEnabled(boolean b);
  113.     public boolean isEnabled();
  114.  
  115.     /**
  116.      * Add or remove a PropertyChange listener. Containers and attached
  117.      * components use these methods to register interest in this Action
  118.      * object. When its enabled state or other property changes,
  119.      * the registered listeners are informed of the change.
  120.      */
  121.     public void addPropertyChangeListener(PropertyChangeListener listener);
  122.     public void removePropertyChangeListener(PropertyChangeListener listener);
  123.  
  124. }
  125.